---
title: 'Astro DB'
description: Apprenez à utiliser Astro DB, une base de données SQL entièrement gérée, conçue exclusivement pour Astro.
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/db/'
i18nReady: true
---
import { FileTree } from '@astrojs/starlight/components';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import ReadMore from '~/components/ReadMore.astro';
import Since from '~/components/Since.astro';
import { Steps } from '@astrojs/starlight/components';

Astro DB est une base de données SQL entièrement gérée conçue pour l'écosystème Astro. Développez localement dans Astro et déployez vers n'importe quelle base de données compatible libSQL.

Astro DB est une solution complète pour configurer, développer et interroger vos données. Une base de données locale est créée dans `.astro/content.db` chaque fois que vous exécutez `astro dev` pour gérer vos données sans avoir besoin de Docker ou d'une connexion réseau.

## Installation

Installez [l'intégration `@astrojs/db`](/fr/guides/integrations-guide/db/) à l'aide de la commande intégrée `astro add` :

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npx astro add db
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm astro add db
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn astro add db
    ```
  </Fragment>
</PackageManagerTabs>

## Définir votre base de données

L'installation de `@astrojs/db` avec la commande `astro add` créera automatiquement un fichier `db/config.ts` dans votre projet où vous définirez vos tables de base de données :

```ts title="db/config.ts"
import { defineDb } from 'astro:db';

export default defineDb({
  tables: { },
})
```

### Tables

Dans Astro DB, les données sont stockées dans des tables SQL. Les tables structurent vos données en lignes et en colonnes, où les colonnes imposent le type de chaque valeur de ligne.

Définissez vos tables dans votre fichier `db/config.ts` en fournissant la structure des données de votre base de données libSQL existante ou les données que vous collecterez dans une nouvelle base de données. Cela permettra à Astro de générer une interface TypeScript pour interroger cette table à partir de votre projet. Le résultat est une prise en charge complète de TypeScript lorsque vous accédez à vos données avec la saisie semi-automatique des propriétés et la vérification des types.

Pour configurer une table de base de données, importez et utilisez les utilitaires `defineTable()` et `column` depuis `astro:db`. Ensuite, définissez un nom (sensible à la casse) pour votre table et le type de données dans chaque colonne.

Cet exemple configure une table `Comment` avec les colonnes de texte requises pour `author` et `body` et la rend disponible pour votre projet via l'exportation `defineDb()`.

```ts title="db/config.ts" "Comment"
import { defineDb, defineTable, column } from 'astro:db';

const Comment = defineTable({
  columns: {
    author: column.text(),
    body: column.text(),
  }
})

export default defineDb({
  tables: { Comment },
})
```

<ReadMore>Voir la [référence de configuration des tables](/fr/guides/integrations-guide/db/#référence-de-configuration-des-tables) pour une référence complète des options de table.</ReadMore>

### Colonnes

Astro DB prend en charge les types de colonnes suivants :

```ts title="db/config.ts" "column.text()" "column.number()" "column.boolean()" "column.date()" "column.json()"
import { defineTable, column } from 'astro:db';

const Comment = defineTable({
  columns: {
    // Une chaîne de texte.
    author: column.text(),
    // Une valeur entière.
    likes: column.number(),
    // Une valeur vraie ou fausse.
    flagged: column.boolean(),
    // Valeurs de date et d'heure interrogées sous forme d'Objets JavaScript de type date.
    published: column.date(),
    // Un objet JSON non typé.
    metadata: column.json(),
  }
});
```

<ReadMore>Voir la [référence des colonnes de la table](/fr/guides/integrations-guide/db/#référence-de-configuration-des-tables) pour plus de détails.</ReadMore>

### Références des tables

Les relations entre les tables sont un modèle courant dans la conception des bases de données. Par exemple, une table `Blog` peut être en relation étroite avec d'autres tables `Comment`, `Author`, et `Category`.

Vous pouvez définir ces relations entre les tables et les enregistrer dans votre schéma de base de données à l'aide de **colonnes de référence**. Pour établir une relation, vous aurez besoin de :

- Une **colonne identifiant** de la table référencée. Il s'agit généralement d'une colonne `id` avec la propriété `primaryKey`.
- Une colonne sur la table de base pour **stocker l'`id` référencé**. Celle-ci utilise la propriété `references` pour établir une relation.

Cet exemple montre que la colonne `authorId` d'une table `Comment` fait référence à la colonne `id` d'une table `Author`.

```ts title="db/config.ts" {3, 10}
const Author = defineTable({
  columns: {
    id: column.number({ primaryKey: true }),
    name: column.text(),
  }
});

const Comment = defineTable({
  columns: {
    authorId: column.number({ references: () => Author.columns.id }),
    body: column.text(),
  }
});
```

## Alimenter votre base de données pour le développement

En cours de développement, Astro utilisera la configuration de votre base de données pour générer des types locaux en fonction de vos schémas. Ces derniers seront générés à partir de votre fichier de départ à chaque démarrage du serveur de développement et vous permettront d'interroger et de travailler avec la forme de vos données avec la sûreté du typage et la saisie semi-automatique.

Vous n'aurez pas accès aux données de production pendant le développement, sauf si vous vous [connectez à une base de données distante](#connexion-à-des-bases-de-données-distantes) pendant le développement. Cela protège vos données tout en vous permettant de tester et de développer avec une base de données fonctionnelle et la sûreté du typage.

Pour introduire des données de développement à des fins de test et de débogage dans votre projet Astro, créez un fichier `db/seed.ts`. Importez à la fois l'objet `db` et vos tables définies dans `astro:db`. Puis insérez des données initiales dans chaque table. Ces données de développement doivent correspondre à la forme de votre schéma de base de données et de vos données de production.

L'exemple suivant définit deux lignes de données de développement pour une table `Comment` et une table `Author` :

```ts title="db/seed.ts"
import { db, Comment, Author } from 'astro:db';

export default async function() {
  await db.insert(Author).values([
    { id: 1, name: "Kasim" },
    { id: 2, name: "Mina" },
  ]);

  await db.insert(Comment).values([
    { authorId: 1, body: 'Nous espérons que vous aimez Astro DB !' },
    { authorId: 2, body: 'Profitez-en !'},
  ])
}
```

Votre serveur de développement redémarrera automatiquement votre base de données chaque fois que ce fichier sera modifié, en régénérant vos types et en initialisant ces données de développement à partir de `seed.ts` à chaque fois.

## Connecter une base de données libSQL pour la production

Astro DB peut se connecter à n'importe quelle base de données libSQL locale ou à n'importe quel serveur qui expose le protocole distant libSQL, qu'il soit géré ou auto-hébergé.

Pour connecter Astro DB à une base de données libSQL, définissez les variables d'environnement suivantes obtenues auprès de votre fournisseur de base de données :

- `ASTRO_DB_REMOTE_URL` : l'URL de connexion à l'emplacement de votre base de données libSQL locale ou distante. Cela peut inclure des [options de configuration d'URL](#options-de-configuration-durl-distantes) telles que la synchronisation et le chiffrement en tant que paramètres.
- `ASTRO_DB_APP_TOKEN` : le jeton d'authentification de votre serveur libSQL. Ceci est nécessaire pour les bases de données distantes et n'est pas nécessaire pour [les bases de données locales comme les fichiers ou les bases de données en mémoire](#schéma-durl-et-hôte).

Selon votre service, vous pouvez avoir accès à une interface CLI ou à une interface web pour récupérer ces valeurs. La section suivante illustre la connexion à Turso et la définition de ces valeurs à titre d'exemple, mais vous êtes libre d'utiliser n'importe quel fournisseur.

### Premiers pas avec Turso

Turso est l'entreprise à l'origine de [libSQL](https://github.com/tursodatabase/libsql), le fork open source de SQLite qui alimente Astro DB. Ils fournissent une plate-forme de base de données libSQL entièrement gérée et sont entièrement compatibles avec Astro.

Les étapes ci-dessous vous guideront tout au long du processus d'installation de la CLI de Turso, de connexion (ou d'inscription), de création d'une nouvelle base de données, d'obtention des variables d'environnement requises et de transmission du schéma à la base de données distante.

<Steps>

1. Installez la [CLI de Turso](https://docs.turso.tech/cli/installation).

2. [Connectez-vous ou inscrivez-vous](https://docs.turso.tech/cli/authentication) à Turso.

3. Créez une nouvelle base de données. Dans cet exemple, le nom de la base de données est `andromeda`.

   ```sh "andromeda"
   turso db create andromeda
   ```

4. Exécutez la commande `show` pour voir les informations sur la base de données nouvellement créée :

   ```sh "andromeda"
   turso db show andromeda
   ```

   Copiez la valeur `URL` et définissez-la comme valeur pour `ASTRO_DB_REMOTE_URL`.
   

   ```dotenv title=".env" "libsql://andromeda-houston.turso.io"
   ASTRO_DB_REMOTE_URL=libsql://andromeda-houston.turso.io
   ```

5. Créez un nouveau jeton pour authentifier les requêtes vers la base de données :

   ```sh "andromeda"
   turso db tokens create andromeda
   ```

   Copiez la sortie de la commande et définissez-la comme valeur pour `ASTRO_DB_APP_TOKEN`.

   ```dotenv title=".env" add={2} "eyJhbGciOiJF...3ahJpTkKDw"
   ASTRO_DB_REMOTE_URL=libsql://andromeda-houston.turso.io
   ASTRO_DB_APP_TOKEN=eyJhbGciOiJF...3ahJpTkKDw
   ```

6. Transférez vos schéma et métadonnées de base de données vers la nouvelle base de données Turso.

   ```sh
   astro db push --remote
   ```

7. Félicitations, vous avez maintenant une base de données connectée ! Accordez-vous une pause. 👾

   ```sh
   turso relax
   ```

</Steps>

Pour découvrir davantage de fonctionnalités de Turso, consultez la [documentation de Turso](https://docs.turso.tech).

### Connexion à des bases de données distantes

Astro DB vous permet de vous connecter à des bases de données locales et distantes. Par défaut, Astro utilise un fichier de base de données local pour les commandes `dev` et `build`, recréant des tables et insérant des données de développement à chaque fois.

Pour vous connecter à une base de données distante hébergée, utilisez l'option `--remote`. Celle-ci permet un accès en lecture et en écriture à votre base de données distante, ce qui vous permet d'[accepter et de conserver les données utilisateur](#insérer) dans les environnements de production.

Configurez votre commande de compilation pour utiliser l'option `--remote` :

```json title="package.json" "--remote"
{
  "scripts": {
    "build": "astro build --remote"
  }
}
```

Vous pouvez également utiliser l'option directement dans la ligne de commande :

```bash
# Compiler avec une connexion à distance
astro build --remote

# Développer avec une connexion à distance
astro dev --remote
```

:::caution
Soyez prudent lorsque vous utilisez `--remote` en développement. Cela entraîne la connexion à votre base de données de production en direct et toutes les modifications (insertions, mises à jour, suppressions) seront conservées.
:::

L'option `--remote` utilise la connexion à la base de données distante à la fois localement pendant la compilation et sur le serveur. Assurez-vous de définir les variables d'environnement nécessaires à la fois dans votre environnement de développement local et sur votre plateforme de déploiement. De plus, vous devrez peut-être [configurer le mode web](/fr/guides/integrations-guide/db/#mode) pour les environnements d'exécution n'utilisant pas Node.js tels que Cloudflare Workers ou Deno.

Lors du déploiement de votre projet Astro DB, assurez-vous que la commande de compilation de votre plate-forme de déploiement est définie sur `npm run build` (ou l'équivalent pour votre gestionnaire de paquets) pour utiliser l'option `--remote` configurée dans votre fichier `package.json`.

### Options de configuration d'URL distantes

La variable d'environnement `ASTRO_DB_REMOTE_URL` configure l'emplacement de votre base de données ainsi que d'autres options telles que la synchronisation et le chiffrement.

#### Schéma d'URL et hôte

libSQL prend en charge HTTP et WebSockets comme protocole de transport pour un serveur distant. Il prend également en charge l'utilisation d'un fichier local ou d'une base de données en mémoire. Ceux-ci peuvent être configurés à l'aide des schémas d'URL suivants dans l'URL de connexion :

- `memory:` utilisera une base de données en mémoire. L'hôte doit être vide dans ce cas.
- `file:` utilisera un fichier local. L'hôte est le chemin d'accès au fichier (`file:path/to/file.db`).
- `libsql:` utilisera un serveur distant via le protocole préféré par la bibliothèque (cela peut être différent selon les versions). L'hôte est l'adresse du serveur (`libsql://your.server.io`).
- `http:` utilisera un serveur distant via HTTP. `https:` peut être utilisé pour activer une connexion sécurisée. L'hôte est le même que pour `libsql:`.
- `ws:` utilisera un serveur distant via WebSockets. `wss:` peut être utilisé pour activer une connexion sécurisée. L'hôte est le même que pour `libsql:`.

Les détails de la connexion libSQL (par exemple, la clé de chiffrement, la réplication, l'intervalle de synchronisation) peuvent être configurés comme paramètres de requête dans l'URL de connexion à distance.

Par exemple, pour qu'un fichier local chiffré fonctionne comme une réplique intégrée sur un serveur libSQL, vous pouvez définir les variables d'environnement suivantes :

```dotenv title=".env"
ASTRO_DB_REMOTE_URL=file://local-copy.db?encryptionKey=your-encryption-key&syncInterval=60&syncUrl=libsql%3A%2F%2Fyour.server.io
ASTRO_DB_APP_TOKEN=token-to-your-remote-url
```

:::caution
L'utilisation d'un fichier de base de données est une fonctionnalité avancée et des précautions doivent être prises lors du déploiement pour éviter de remplacer votre base de données et de perdre vos données de production.

De plus, cette méthode ne fonctionnera pas dans les déploiements sans serveur, car le système de fichiers n’est pas conservé dans ces environnements.
:::

#### `encryptionKey`

libSQL prend en charge nativement les bases de données chiffrées. La transmission de ce paramètre de recherche activera le chiffrement à l'aide de la clé donnée :

```dotenv title=".env"
ASTRO_DB_REMOTE_URL=file:path/to/file.db?encryptionKey=your-encryption-key
```

#### `syncUrl`

Les répliques intégrées sont une fonctionnalité des clients libSQL qui crée une copie synchronisée complète de votre base de données sur un fichier local ou en mémoire pour des lectures ultra-rapides. Les écritures sont envoyées vers une base de données distante définie sur `syncUrl` et synchronisées avec la copie locale.

Utilisez cette propriété pour transmettre une URL de connexion distincte afin de transformer la base de données en une réplique intégrée d'une autre base de données. Cela ne doit être utilisé qu'avec les schémas `file:` et `memory:`. Le paramètre doit être codé au format URL.

Par exemple, pour avoir une réplique intégrée en mémoire d'une base de données sur `libsql://votre.server.io`, vous pouvez définir l'URL de connexion comme suit :

```dotenv title=".env"
ASTRO_DB_REMOTE_URL=memory:?syncUrl=libsql%3A%2F%2Fyour.server.io
```

#### `syncInterval`

Intervalle en secondes entre les synchronisations de répliques intégrées. Par défaut, la synchronisation se fait uniquement au démarrage et après les écritures.

Cette propriété n'est utilisée que lorsque `syncUrl` est également définie. Par exemple, pour configurer une réplique intégrée en mémoire afin qu'elle se synchronise toutes les minutes, définissez la variable d'environnement suivante :

```dotenv title=".env"
ASTRO_DB_REMOTE_URL=memory:?syncUrl=libsql%3A%2F%2Fyour.server.io&syncInterval=60
```

## Interroger votre base de données

Vous pouvez interroger votre base de données depuis n'importe quelle [page Astro](/fr/basics/astro-pages/#pages-astro) ou [point de terminaison](/fr/guides/endpoints/) ou [action](/fr/guides/actions/) de votre projet en utilisant l'ORM `db` et le constructeur de requêtes fourni.

### Drizzle ORM

```ts
import { db } from 'astro:db';
```

Astro DB comprend un client intégré [Drizzle ORM](https://orm.drizzle.team/). Il n'y a pas d'installation ou de configuration manuelle requise pour utiliser le client. Le client Astro DB `db` est automatiquement configuré pour communiquer avec votre base de données (locale ou distante) lorsque vous lancez Astro. Il utilise la définition exacte de votre schéma de base de données pour des requêtes SQL avec sûreté du typage et des erreurs TypeScript lorsque vous référencez une colonne ou une table qui n'existe pas.

### Sélectionner

L'exemple suivant sélectionne toutes les lignes d'une table `Comment`. Cela renvoie le tableau complet des données de développement provenant de `db/seed.ts`, qui est alors disponible pour être utilisé dans votre modèle de page :

```astro title="src/pages/index.astro"
---
import { db, Comment } from 'astro:db';

const comments = await db.select().from(Comment);
---

<h2>Commentaires</h2>

{
  comments.map(({ author, body }) => (
    <article>
      <p>Auteur : {author}</p>
      <p>{body}</p>
    </article>
  ))
}
```

<ReadMore>Consultez la [référence de l'API `select()` de Drizzle](https://orm.drizzle.team/docs/select) pour un aperçu complet.</ReadMore>

### Insérer

Pour accepter les entrées de l'utilisateur, comme le traitement des demandes de formulaire et l'insertion de données dans votre base de données hébergée à distance, configurez votre projet Astro pour [un rendu à la demande](/fr/guides/on-demand-rendering/) et [ajoutez un adaptateur](/fr/guides/on-demand-rendering/#ajouter-un-adaptateur) pour votre environnement de déploiement.

Cet exemple insère une ligne dans une table `Comment` sur la base d'une requête POST de formulaire analysée :

```astro
---
// src/pages/index.astro
import { db, Comment } from 'astro:db';

if (Astro.request.method === 'POST') {
  // Analyser les données du formulaire
  const formData = await Astro.request.formData();
  const author = formData.get('author');
  const content = formData.get('content');
  if (typeof author === 'string' && typeof content === 'string') {
    // Insérer les données du formulaire dans la table Comment
    await db.insert(Comment).values({ author, content });
  }
}

// Affiche la nouvelle liste des commentaires sur chaque demande
const comments = await db.select().from(Comment);
---

<form method="POST" style="display: grid">
	<label for="author">Auteur</label>
	<input id="author" name="author" />

	<label for="body">Message</label>
	<textarea id="body" name="body"></textarea>

	<button type="submit">Envoyer</button>
</form>

<!-- Afficher les commentaires -->
```

Vous pouvez également utiliser [Astro Actions](/fr/guides/actions/) pour insérer des données dans une table Astro DB. L'exemple suivant insère une ligne dans une table `Comment` à l'aide d'une action :

```ts
// src/actions/index.ts
import { db, Comment } from 'astro:db';
import { defineAction } from 'astro:actions';
import { z } from 'astro:schema';

export const server = {
  addComment: defineAction({
    // Les actions incluent la sûreté du typage avec Zod, supprimant ainsi le
    // besoin de vérifier si typeof {value} === 'string' dans vos pages
    input: z.object({
      author: z.string(),
      body: z.string(),
    }),
    handler: async (input) => {
      const updatedComments = await db
        .insert(Comment)
        .values(input)
        .returning(); // Renvoie les commentaires mis à jour
      return updatedComments;
    },
  }),
};
```

<ReadMore>

Consultez la [référence de l'API `insert()` de Drizzle] (https://orm.drizzle.team/docs/insert) pour une vue d'ensemble complète.

</ReadMore>

### Supprimer

Vous pouvez également interroger votre base de données à partir d'un point de terminaison d'API. Cet exemple supprime une ligne d'une table `Comment` par le paramètre `id` :

```ts
// src/pages/api/comments/[id].ts
import type { APIRoute } from "astro";
import { db, Comment, eq } from 'astro:db';

export const DELETE: APIRoute = async (ctx) => {
  await db.delete(Comment).where(eq(Comment.id, ctx.params.id ));
  return new Response(null, { status: 204 });
}
```

<ReadMore>

Consultez la [référence de l'API `delete()` de Drizzle](https://orm.drizzle.team/docs/delete) pour un aperçu complet.

</ReadMore>

### Filtrage

Pour rechercher les résultats d'une table en fonction d'une propriété spécifique, utilisez [les options de Drizzle pour les sélections partielles](https://orm.drizzle.team/docs/select#partial-select). Par exemple, ajoutez [un appel à `.where()`](https://orm.drizzle.team/docs/select#filtering) à votre requête `select()` et passez la comparaison que vous voulez faire.

L'exemple suivant recherche toutes les lignes d'une table `Comment` qui contiennent l'expression « Astro DB ». Utilisez [l'opérateur `like()`](https://orm.drizzle.team/docs/operators#like) pour vérifier si une phrase est présente dans le `body` :


```astro title="src/pages/index.astro"
---
import { db, Comment, like } from 'astro:db';

const comments = await db.select().from(Comment).where(
    like(Comment.body, '%Astro DB%')
);
---
```

### Utilitaires de Drizzle

Tous les utilitaires de Drizzle permettant de construire des requêtes sont exposés à partir du module `astro:db`. Cela inclut :

- [Les opérateurs de filtre](https://orm.drizzle.team/docs/operators) comme `eq()` et `gt()`
- [Les aides à l'agrégation](https://orm.drizzle.team/docs/select#aggregations-helpers) comme `count()`
- [L'aide `sql`](https://orm.drizzle.team/docs/sql) pour écrire des requêtes SQL brutes

```ts
import { eq, gt, count, sql } from 'astro:db';
```

### Les relations

Vous pouvez interroger des données liées provenant de plusieurs tables à l'aide d'une liaison SQL. Pour créer une requête de liaison, ajoutez un opérateur de liaison à votre déclaration `db.select()`. Chaque fonction accepte une table à l'origine de la liaison et une condition pour faire correspondre les lignes entre les deux tables.

Cet exemple utilise une fonction `innerJoin()` pour faire la liaison entre les auteurs de commmentaires (`Comment`) et leurs informations `Author` sur la base de la colonne `authorId`. Cette fonction retourne un tableau d'objets avec chaque ligne `Author` et `Comment` comme propriétés de premier niveau :

```astro title="src/pages/index.astro"
---
import { db, eq, Comment, Author } from 'astro:db';

const comments = await db.select()
  .from(Comment)
  .innerJoin(Author, eq(Comment.authorId, Author.id));
---

<h2>Commentaires</h2>

{
  comments.map(({ Author, Comment }) => (
    <article>
      <p>Auteur : {Author.name}</p>
      <p>{Comment.body}</p>
    </article>
  ))
}
```

<ReadMore>

Voir la [référence de liaison Drizzle](https://orm.drizzle.team/docs/joins#join-types) pour tous les opérateurs de liaison disponibles et les options de configuration.

</ReadMore>

### Transactions par paquets

Toutes les requêtes de bases de données distantes sont effectuées sous la forme d'une requête réseau. Vous pouvez avoir besoin de regrouper les requêtes en une seule transaction lorsque vous effectuez un grand nombre de requêtes, ou de procéder à des retours en arrière automatiques en cas d'échec d'une requête.

Cet exemple permet de lancer plusieurs lignes en une seule requête à l'aide de la méthode `db.batch()` :

```ts
// db/seed.ts
import { db, Author, Comment } from 'astro:db';

export default async function () {
  let queries;
  // Envoyez 100 exemples de commentaires dans votre base de données distante
  // avec une seule demande de réseau.
  for (let i = 0; i < 100; i++) {
    queries.push(db.insert(Comment).values({ body: `Test comment ${i}` }));
  }
  await db.batch(queries);
}
```

<ReadMore>

Voir la documentation [de `db.batch()` sur Drizzle](https://orm.drizzle.team/docs/batch-api) pour plus de détails.

</ReadMore>

## Envoi des modifications vers votre base de données

Vous pouvez transférer les modifications apportées pendant le développement vers votre base de données.

### Pousser les schémas de table

Votre schéma de table peut changer au fil du temps à mesure que votre projet se développe. Vous pouvez tester en toute sécurité les modifications de configuration localement et les transférer vers votre base de données distante lors du déploiement.

Vous pouvez transférer les modifications de votre schéma local vers votre base de données distante via la CLI à l'aide de la commande `astro db push --remote` :

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npm run astro db push --remote
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm astro db push --remote
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn astro db push --remote
    ```
  </Fragment>
</PackageManagerTabs>

Cette commande vérifiera que vos modifications locales peuvent être effectuées sans perte de données et, si nécessaire, vous suggérera comment apporter des modifications en toute sécurité à votre schéma afin de résoudre les conflits.

#### Pousser les changements majeurs de schéma

:::caution
__Cela détruira votre base de données__. N'exécutez cette commande que si vous n'avez pas besoin de vos données de production.
:::

Si vous devez modifier le schéma de votre table d'une manière incompatible avec vos données existantes hébergées sur votre base de données distante, vous devrez réinitialiser votre base de données de production.

Pour pousser une mise à jour du schéma de table qui inclut un changement radical, ajoutez l'option `--force-reset` pour réinitialiser toutes les données de production :

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npm run astro db push --remote --force-reset
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm astro db push --remote --force-reset
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn astro db push --remote --force-reset
    ```
  </Fragment>
</PackageManagerTabs>

### Renommer des tables

Il est possible de renommer une table après avoir transmis votre schéma à votre base de données distante.

Si vous **n'avez pas de données de production importantes**, alors vous pouvez [réinitialiser votre base de données](#pousser-les-changements-majeurs-de-schéma) en utilisant l'option `--force-reset`. Celle-ci supprimera toutes les tables de la base de données et en créera de nouvelles afin qu'elles correspondent exactement à votre schéma actuel.

Pour renommer une table tout en préservant vos données de production, vous devez effectuer une série de modifications non cassantes pour transférer votre schéma local vers votre base de données distante en toute sécurité.

L'exemple suivant renomme une table `Comment` en `Feedback` :

<Steps>

1. Dans le fichier de configuration de votre base de données, ajoutez la propriété `deprecated: true` à la table que vous voulez renommer :

    ```ts title="db/config.ts" ins={2}
    const Comment = defineTable({
      deprecated: true,
    	columns: {
    		author: column.text(),
    		body: column.text(),
  		}
    });
    ```

2. Ajoutez un nouveau schéma de table (correspondant exactement aux propriétés de la table existante) avec le nouveau nom :

	  ```ts title="db/config.ts" ins={8-14}
    const Comment = defineTable({
        deprecated: true,
    	columns: {
    		author: column.text(),
    		body: column.text(),
  		}
    });

	  const Feedback = defineTable({
        columns: {
          author: column.text(),
          body: column.text(),
        }
    });
    ```
3. [Poussez vers votre base de données distante](#pousser-les-schémas-de-table) avec `astro db push --remote`. Cela ajoutera la nouvelle table et marquera l'ancienne comme obsolète.
4. Mettez à jour le code de votre projet local pour utiliser la nouvelle table au lieu de l'ancienne. Il se peut que vous deviez également migrer des données vers la nouvelle table.
5. Une fois que vous êtes sûr que l'ancienne table n'est plus utilisée dans votre projet, vous pouvez supprimer le schéma de votre `config.ts` :
		```ts title="db/config.ts" del={1-7}
    const Comment = defineTable({
          deprecated: true,
    	  columns: {
    		  author: column.text(),
    		  body: column.text(),
  		  }
    });

	  const Feedback = defineTable({
          columns: {
            author: column.text(),
            body: column.text(),
          }
    });
    ```
6. Poussez à nouveau vers votre base de données distante avec `astro db push --remote`. L'ancienne table sera supprimée, ne laissant que la nouvelle table renommée.
</Steps>

### Pousser les données d'une table

Vous devrez peut-être transférer des données vers votre base de données distante pour l'amorçage ou les migrations de données. Vous pouvez créer un fichier `.ts` avec le module `astro:db` pour écrire des requêtes avec sûreté du typage. Ensuite, exécutez le fichier sur votre base de données distante à l'aide de la commande `astro db execute <file-path> --remote` :

Les commentaires suivants peuvent être initiés à l'aide de la commande `astro db execute db/seed.ts --remote` :

```ts
// db/seed.ts
import { Comment } from 'astro:db';

export default async function () {
  await db.insert(Comment).values([
    { authorId: 1, body: "J'espère que vous aimerez Astro DB !" },
    { authorId: 2, body: 'Profitez !' },
  ])
}
```

<ReadMore>

Consultez la [référence de la CLI](/fr/guides/integrations-guide/db/#référence-de-la-cli-dastro-db) pour une liste complète des commandes.

</ReadMore>

## Construire des intégrations Astro DB

Les [intégrations Astro](/fr/reference/integrations-reference/) permettent d'étendre les projets des utilisateurs avec des tables Astro DB supplémentaires et des données de départ.

Utilisez la méthode `extendDb()` dans le hook `astro:db:setup` pour enregistrer des fichiers de configuration et de données initiales (_seed_) Astro DB supplémentaires.
L'aide `defineDbIntegration()` fournit la prise en charge de TypeScript et l'auto-complétion pour le hook `astro:db:setup`.

```js {8-13}
// my-integration/index.ts
import { defineDbIntegration } from '@astrojs/db/utils';

export default function MyIntegration() {
  return defineDbIntegration({
    name: 'my-astro-db-powered-integration',
    hooks: {
      'astro:db:setup': ({ extendDb }) => {
        extendDb({
          configEntrypoint: '@astronaut/my-package/config',
          seedEntrypoint: '@astronaut/my-package/seed',
        });
      },
      // Autres hooks d'intégration...
    },
  });
}
```

Les fichiers de [configuration](#définir-votre-base-de-données) et de [données initiales](#alimenter-votre-base-de-données-pour-le-développement) des intégrations suivent le même format que leurs équivalents définis par l'utilisateur.

### Opérations avec sûreté du typage dans les intégrations

Lorsque vous travaillez sur des intégrations, il se peut que vous ne puissiez pas bénéficier des types de table générés par Astro et exportés depuis `astro:db`.
Pour une sûreté totale du typage, utilisez l'utilitaire `asDrizzleTable()` pour créer un objet de référence de table que vous pouvez utiliser pour les opérations de base de données.

Par exemple, dans le cas d'une intégration mettant en place la table de base de données `Pets` suivante :

```js
// my-integration/config.ts
import { defineDb, defineTable, column } from 'astro:db';

export const Pets = defineTable({
  columns: {
    name: column.text(),
    species: column.text(),
  },
});

export default defineDb({ tables: { Pets } });
```

Le fichier de données initiales (« seed ») peut importer `Pets` et utiliser `asDrizzleTable()` pour insérer des lignes dans votre table avec vérification du type :

```js {2,7} /typeSafePets(?! )/
// my-integration/seed.ts
import { asDrizzleTable } from '@astrojs/db/utils';
import { db } from 'astro:db';
import { Pets } from './config';

export default async function() {
  const typeSafePets = asDrizzleTable('Pets', Pets);

  await db.insert(typeSafePets).values([
    { name: 'Palomita', species: 'cat' },
    { name: 'Pan', species: 'dog' },
  ]);
}
```

La valeur retournée par `asDrizzleTable('Pets', Pets)` est équivalente à `import { Pets } from 'astro:db'`, mais elle est disponible même si la génération de type d'Astro ne peut pas fonctionner.
Vous pouvez l'utiliser dans tout code d'intégration qui doit interroger ou insérer dans la base de données.




### Migrer depuis Astro Studio vers Turso

<Steps>

1. Dans le [tableau de bord de Studio](https://studio.astro.build/), accédez au projet que vous souhaitez migrer. Dans l'onglet Paramètres, utilisez le bouton « Exporter la base de données » pour télécharger une copie de votre base de données.
2. Suivez les instructions officielles pour [installer la CLI de Turso](https://docs.turso.tech/cli/installation) et [inscrivez-vous ou connectez-vous](https://docs.turso.tech/cli/authentication) à votre compte Turso.
3. Créez une nouvelle base de données sur Turso en utilisant la commande `turso db create`.
   ```sh
   turso db create [database-name]
   ```
4. Récupérez l'URL de la base de données à l'aide de Turso CLI et utilisez-la comme variable d'environnement `ASTRO_DB_REMOTE_URL`.
   ```sh
   turso db show [database-name]
   ```
   ```dotenv
   ASTRO_DB_REMOTE_URL=[your-database-url]
   ```
5. Créez un jeton pour accéder à votre base de données et utilisez-le comme variable d'environnement `ASTRO_DB_APP_TOKEN`.
   ```sh
   turso db tokens create [database-name]
   ```
   ```dotenv
   ASTRO_DB_APP_TOKEN=[your-app-token]
   ```
6. Transférez votre schéma de base de données et vos métadonnées vers la nouvelle base de données Turso.
   ```sh
   astro db push --remote
   ```
7. Importez l'exportation de la base de données de l’étape 1 dans votre nouvelle base de données Turso.
   ```sh
   turso db shell [database-name] < ./path/to/dump.sql
   ```
8. Une fois que vous avez confirmé que votre projet se connecte à la nouvelle base de données, vous pouvez supprimer le projet en toute sécurité dans Astro Studio.

</Steps>
